Skip to content

docs: full documentation audit (rustdoc + mdBook)#28

Merged
eshork merged 5 commits into
mainfrom
docs_audit
Jul 12, 2026
Merged

docs: full documentation audit (rustdoc + mdBook)#28
eshork merged 5 commits into
mainfrom
docs_audit

Conversation

@eshork

@eshork eshork commented Jul 12, 2026

Copy link
Copy Markdown
Collaborator

Summary

Full documentation audit across all 4 workspace crates (rustdoc) plus the mdBook docs/ site, following up on the recently-merged blind-relay feature (#27). Documentation only — no behavior changes.

Audited via 5 parallel read-only review passes, then fixed via 9 parallel implementation passes; every change independently spot-checked afterward (doc-link fixes verified against cargo doc, README manpage count verified against a real peeroxide init --man-pages run, etc.).

What changed, by commit

  • libudx: documented the entire native/header.rs wire-format module (Header, flag constants, SackRange, encode/decode) — previously had zero doc comments despite being on VISIBILITY_POLICY.md's "must stay pub" reference-ecosystem-pins list.
  • peeroxide-dht: fixed all 8 cargo doc warnings (7 broken intra-doc links + 1 public-doc-linking-to-private-item leak). Rewrote blind_relay.rs/relay_service.rs module docs to cover the pairing/session model, idle-session-timeout, stream teardown, and the relay self-announce mechanism. Corrected a misleading "unthrottled like Node" claim.
  • peeroxide: documented relay-client support (SwarmConfig::relay_through/relay_address) in swarm.rs::spawn() and crate-level docs.
  • peeroxide-cli: fixed 5 pre-existing broken doc links. Updated README.md (added the relay command to the table, fixed the manpage count 9→10, clarified dd v2-is-default). Also fixed a real stale-help-text bug: --idle-session-timeout/--relay-idle-session-timeout help text still claimed idle-session sweeping was "not yet enforced" — stale since that feature actually shipped in peeroxide-dht 1.7.0.
  • mdBook (docs/): the biggest gap — added brand-new docs/src/node/overview.md and docs/src/relay/{overview,architecture}.md chapters, since the node and relay commands (including the entire blind-relay feature) had zero user-facing documentation. Fixed a stale appendices/tracing.md claim that relay had no logging. Wired new chapters into SUMMARY.md/introduction.md navigation. Updated docs/AGENTS.md.

Testing

  • cargo test --workspace --lib --bins — 900 tests passing
  • cargo clippy --workspace --all-targets -- -D warnings — clean
  • cargo doc --workspace --no-deps — clean (only the pre-existing, unrelated bin/lib name-collision warning remains)
  • mdbook build docs/ — clean, no errors

Versions

No version bumps — pure documentation/help-text fixes, no public API or behavior changes.

Checklist

  • Both test suites pass locally (live network suite not affected by doc-only changes; not re-run this pass)
  • Clippy clean (-D warnings)
  • No public API breaking changes
  • N/A — no new public API surface introduced (visibility policy not applicable)
  • CHANGELOG updated (peeroxide-cli — the help-text correction)
  • N/A — no version bumps needed
  • No task-artifact files committed

eshork and others added 5 commits July 12, 2026 14:49
Header, HEADER_SIZE/MAGIC/VERSION, all FLAG_* constants, HeaderError,
SackRange, and the encode/decode/encode_sack/decode_sack functions had
zero rustdoc despite Header and the flag constants being on
VISIBILITY_POLICY.md's reference-ecosystem-pins list (must-stay-pub
API). Adds a module-level //! overview plus accurate /// docs for
every item, describing the real wire layout, little-endian encoding,
ACK semantics, and SACK half-open range semantics.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fixes 8 cargo-doc warnings:
- hyperdht.rs:1168 broken link to connect_with_nodes -> Self::connect_with_nodes
- relay_service.rs module docs: 6 broken links (HyperDhtHandle, ServerEvent,
  BlindRelaySession, BlindRelayServer, UdxStream::relay_to, Io) fixed with
  fully-qualified paths
- io.rs:829 public doc on reply_to linked to a private item
  (Self::send_reply_deferred) -> reworded to prose/code-span, no longer a
  broken link

Expands module-level docs, previously thin/stale relative to the rapid
recent feature work:
- blind_relay.rs: explains the pairing/session model, idle-session-timeout
  hardening (peeroxide-only, no Node precedent), and stream teardown on
  unpair/session-close (1:1 Node precedent). Corrects a misleading claim
  that the relay is "unthrottled like Node" - peeroxide does impose its
  own configurable (generous-by-default) limits.
- relay_service.rs: documents the self-announce mechanism (announces
  hash(pubkey) to the DHT at startup plus a ~10min refresh so Node.js
  clients can discover the relay via findPeer), periodic idle-session and
  pairing sweep, and stream-teardown lifecycle.
- lib.rs: adds relay_service to the crate-level module overview table.

Documentation only, no behavior changes. cargo doc/clippy/test all clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
spawn()'s doc comment read like a basic direct/holepunched-only launcher
and didn't mention that a swarm can be configured to pair through a
blind-relay server via SwarmConfig::relay_through/relay_address. Crate-
level lib.rs docs updated similarly.

Documentation only, no behavior changes. cargo doc/clippy/test all clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…pdate README

Fixes 5 pre-existing cargo-doc warnings:
- chat/display.rs:87-88 [`render_to`] -> [`Self::render_to`]
- chat/tui/mod.rs:76 [`install_global`] -> [`super::install_global_notice_sink`]
- deaddrop/v2/keys.rs:6,8 array-index-style [i]/[0] misparsed as intra-doc
  links -> wrapped in code spans

Fixes a real, user-facing inaccuracy found while cross-checking a new
mdBook chapter against live --help output: `--idle-session-timeout` /
`--relay-idle-session-timeout` help text still claimed idle-session
sweeping was "not yet enforced" -- true when the flags were first added,
but stale since idle-session-timeout enforcement actually shipped in
peeroxide-dht 1.7.0 (sweep_idle_sessions is wired into run_relay_server's
periodic sweep task). Corrected in both relay.rs and node.rs.

README.md: adds the relay command to the command table (previously
omitted entirely), corrects the manpage count from 9 to 10 (verified by
actually running `peeroxide init --man-pages`), and clarifies that dd v2
is the current default protocol (--v1 opts into the legacy path).

Documentation only, no behavior changes. cargo doc/build/clippy all clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ntent

Closes the biggest gap found in a full documentation audit: the
peeroxide node command and the entire blind-relay feature (peeroxide
relay, node --relay) had zero mdBook coverage anywhere, despite being
the focus of the last several development sessions.

Adds:
- docs/src/node/overview.md -- the peeroxide node command: what it does,
  basic/private-mesh/--relay usage, bootstrap resolution, flags.
- docs/src/relay/overview.md -- blind relay: what "blind" means, the two
  ways to run one (dedicated `relay` vs courtesy `node --relay`), all
  configurable limits/timeouts with real defaults, how clients opt in
  (SwarmConfig::relay_through/relay_address, PEEROXIDE_FORCE_RELAY for
  cp), and a security-notes section on what a relay can/cannot observe.
- docs/src/relay/architecture.md -- internals: token-pairing model, the
  Protomux "blind-relay" control channel, blind UDX-layer forwarding via
  relay_to, teardown/idle-timeout behavior (noting which parts have Node
  precedent and which are peeroxide-only hardening), and the relay
  self-announce mechanism for DHT discoverability.
- SUMMARY.md/introduction.md: wired both new chapters into navigation,
  corrected the primary-command count (eight -> nine).

Fixes:
- appendices/tracing.md: the relay row said logging was "(none
  currently)" -- stale, relay logging is now extensive. Replaced with
  the real tracing targets/events across relay.rs, node.rs,
  relay_service.rs, and blind_relay.rs.
- docs/src/node/overview.md's own idle-session-timeout flag description
  initially copied a stale "not yet enforced" claim from the CLI help
  text being fixed in the same pass -- corrected to match actual current
  behavior.
- docs/AGENTS.md: added node/ (and the general new-command-chapter
  convention covering relay/) to the structure notes; verified
  mdbook-mermaid is still genuinely needed (real diagram usage found in
  several existing chapters), left that instruction as-is.

mdbook build docs/ succeeds cleanly with no warnings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@eshork eshork merged commit afecfb6 into main Jul 12, 2026
5 checks passed
@eshork eshork deleted the docs_audit branch July 12, 2026 19:05
@github-actions github-actions Bot mentioned this pull request Jul 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant